=========================================================================
ISTRUZIONI e SPECIFICHE per il PRIMO ESERCIZIO del PROGETTO di LCS 07/08
========================================================================

Il progetto prevede la realizzazione di tre esercizi. Il primo e' descritto in
questo README.

Il primo esercizio del progetto prevede l'implementazione di una libreria che
realizza dei grafi non orientati.

Questo esercizio e' realizzabile usando esclusivamente C sequenziale (vedi
programma LLS).


------------------------------------------------
Estrarre il materiale da lcsgraphs_kitf1.tar  
------------------------------------------------
Creare una directory temporanea, copiare lcsgraphs_kit1.tar
nella directory e spostarsi nella directory appena creata. Es.

$$ mkdir Frammento1
$$ mv lcsgraphs_kit1.tar Frammento1
$$ cd Frammento1

S-tarare i file del primo kit con

$$ tar xvf lcsgraphs_kit1.tar

questa operazione crea nella directory corrente una directory "graphs" che
contiene i seguenti file:

$$ ls graphs/

gruppo-check.pl   README-1
gruppo.txt        graphs.h 
Doxyfile	  test-graph.c	  
Makefile	  README.doxygen

-----------------------------------------------
Descrizione dei file contenuti nel kit
-----------------------------------------------

README-1		: questo file


gruppo-check.pl		: uno script Perl che controlla il formato del file
			  gruppo.txt prima di effettuare la consegna
			  (NON MODIFICARE)

gruppo.txt		: un file di esempio di specifica del gruppo
			  (solo 1 studente per gruppo)
			  (deve essere aggiornato con i dati di chi consegna,
			  secondo il formato esemplificato)

test-graph.c		: un programma di test per il test FINALE del codice
                          prodotto (NON MODIFICARE)

graphs.h		: tipi e prototipi delle funzioni da realizzare
			  nel primo esercizio
			  (NON MODIFICARE)

Makefile		: makefile per il test finale del frammento e la
			  consegna 
			  (NON MODIFICARE nelle parti richieste)

Doxyfile		: file di configurazione per la generazione della
			  documentazione HTML con doxygen (facoltativo)

README.doxygen		:  breve descrizione di doxygen, 
                             con rimandi ai siti rilevanti


------------------------------------------------
Cosa deve essere realizzato per il primo esercizio :
------------------------------------------------

Il primo esercizio prevede la realizzazione di una libreria con cui costruire
grafi non orientati. A ogni nodo del grafo e' univocamente determinato da una
etichetta intera.

Le strutture dati da utilizzare per realizzare la libreria sono definite e
commentate in graphs.h. Nello stesso file sono definiti e commentati i 
prototipi delle funzioni da realizzare.

I commenti in *.h spiegano le strutture dati da utilizzare
il comportamento delle varie funzioni, il significato dei parametri ed
i valori ritornati. La sintassi utilizzata e' quella di doxygen, un tool per
la creazione della documentazione 'tipo javadoc' comunemente utilizzato.
Chi vuole utilizzarlo per la produzione della documentazione puo' leggere
il README.doxygen.

Per generare la documentazione html dei file contenuti nel kit basta invocare

  bash:~$ make docu

e poi visualizzare il file ./html/index.html con un browser.

Le funzioni richieste possono essere realizzate usando un singolo file
chiamato "graphs.c", in questo caso non e' necessario modificare il Makefile
per effettuare test e consegna finale. Altrimenti e' possibile definire un
numero arbitrario di file *.c e *.h ed e' richiesto di modificare il Makefile
affinche' la compilazione avvenga in modo corretto.
Inoltre, in questo caso, e' necessario anche specificare tutti i file da
consegnare (modificando la variabile FILE_DA_CONSEGNARE). In questo caso,
attenzione a consegnare anche il nuovo Makefile!

------------------
Come procedere :
-----------------

0) leggere attentamente il README e capire il funzionamento il codice fornito
   dai docenti 

1) analizzare accuratamente il file test-graph.c per capire il tipo di test
   effettuati 

2) implementare le funzioni richieste in uno o piu' file
   ed effettuare testing preliminare utilizzando un main() sviluppato 
   allo scopo

3) testare il software complessivo con il main() (test-graph.c) fornito dai
  docenti (usando il Makefile). E' necessario prima settare la variabile di
  ambiente MALLOC_TRACE in modo che contenga "./.mtrace.log" e poi
  procedere al test invocando il target "test", cioe' eseguire:

       bash:~$ export MALLOC_TRACE="./.mtrace.log"
       bash:~$ make test

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  directory graphs/
  (2) E' importante che il test venga effettuato solo su
  un programma gia' funzionante altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.

4) preparare la documentazione: ovvero commentare adeguatamente il/i file che
   contengono la soluzione  ed inserire una intestazione contenente il nome
   dello sviluppatore ed una dichiarazione di originalita' 

   /** \file pippo.c
       \author Nino Bixio
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale dell' autore.  */

     Non e' richiesto di preparare anche la documentazione formato
     doxygen. Chi volesse farlo e' invitato a leggere il  README.doxigen.

5) aggiornare il file "gruppo.txt" con nome e dati

6) consegnare il file ESCLUSIVAMENTE eseguendo

      bash:~$ make consegna

   e seguendo le istruzioni. Anche in questo caso occorre  che la variabile
   MALLOC_TRACE sia settata  a "./.mtrace.log".
   Per la consegna e' necessaria l'utility "mpack" installata solo nelle
   macchine dei laboratori H, M ed I. Per consegne da altre macchine e'
   possibile scaricare il binario di 'mpack' dal sito del corso. 


---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) gli eleborati non consegnati con "make consegna" non verranno accettati

2) tutti gli elaborati verranno confrontati fra di loro con tool automatici
   per stabilire eventali situazioni di PLAGIO. Se tali situazioni si
   verificheranno *tutti* gli elaborato coinvolti verranno annullati con
   conseguente perdita del bonus. 

3) Tutti gli studenti coinvolti in un episodio di PLAGIO comprovato dovranno
   re-implementare il frammento incriminato e saranno sottoposti ad una prova
   orale supplementare. In caso di recidive verranno esclusi dalla
   possibilita' di sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO
   IN CORSO.

4) Chi in sede di orale risulta palesemente non essere l'autore del software
   consegnato in uno dei frammenti verra' escluso dalla possibilita' di
   sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO IN CORSO.

5) Tutti i comportamenti scorretti ai punti 3 e 4 verranno segnalati
   ufficialmente al presidente del corso di laurea, che si riserva di
   decidere azioni disciplinari supplementari a quelle sopra descritte.

----------------------------
 VALUTAZIONE DELL'ESERCIZIO:
----------------------------

Gli studenti che consegnano una versione funzionante e ragionevolmente
corretta dell'esercizio entro la data di scadenza accumulano un bonus di 2
punti che verra' sommato al voto finale (vedi lucidi lezioni ed
esercitazioni).

La qualita' del codice consegnato per il primo esercizio verra' valutata come
parte del progetto finale e contribuira' alla votazione assegnata al progetto.
Eventuali caratteristiche in piu' rispetto a quelle strettamente richieste
dalle specifiche date qua (es. documentazione HTML o in altri
formati) verranno valutate in questa sede.
